home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Celestin Apprentice 7
/
Apprentice-Release7.iso
/
Environments
/
PowerLisp 2.01
/
Supplemental Documentation
/
Documentation
/
Chapter 25. Misc. Features
< prev
next >
Wrap
Lisp/Scheme
|
1995-03-28
|
65KB
|
1,364 lines
Common Lisp the Language, 2nd Edition
-------------------------------------------------------------------------------
25. Miscellaneous Features
In this chapter are described various things that don't seem to fit neatly
anywhere else in this book: the compiler, the documentation function, debugging
aids, environment inquiries (including facilities for calculating and measuring
time), and the identity function.
-------------------------------------------------------------------------------
* The Compiler
o Compiler Diagnostics
o Compiled Functions
o Compilation Environment
o Similarity of Constants
* Documentation
* Debugging Tools
* Environment Inquiries
o Time Functions
o Other Environment Inquiries
* Identity Function
-------------------------------------------------------------------------------
25.1. The Compiler
[old_change_begin]
The compiler is a program that may make code run faster by translating programs
into an implementation-dependent form that can be executed more efficiently by
the computer. Most of the time you can write programs without worrying about
the compiler; compiling a file of code should produce an equivalent but more
efficient program. When doing more esoteric things, you may need to think
carefully about what happens at ``compile time'' and what happens at ``load
time.'' Then the difference between the syntaxes #. and #, becomes important,
and the eval-when construct becomes particularly useful.
[old_change_end]
[change_begin]
X3J13 voted in January 1989 (SHARP-COMMA-CONFUSION) to remove #, from the
language.
[change_end]
Most declarations are not used by the Common Lisp interpreter; they may be used
to give advice to the compiler. The compiler may attempt to check your advice
and warn you if it is inconsistent.
Unlike most other Lisp dialects, Common Lisp recognizes special declarations in
interpreted code as well as compiled code. This potential source of
incompatibility between interpreted and compiled code is thereby eliminated in
Common Lisp.
The internal workings of a compiler will of course be highly
implementation-dependent. The following functions provide a standard interface
to the compiler, however.
[old_change_begin]
[Function]
compile name &optional definition
If definition is supplied, it should be a lambda-expression, the interpreted
function to be compiled. If it is not supplied, then name should be a symbol
with a definition that is a lambda-expression; that definition is compiled and
the resulting compiled code is put back into the symbol as its function
definition.
[old_change_end]
[change_begin]
X3J13 voted in October 1988 (COMPILE-ARGUMENT-PROBLEMS) to restate the
preceding paragraph more precisely and to extend the capabilities of compile.
If the optional definition argument is supplied, it may be either a
lambda-expression (which is coerced to a function) or a function to be
compiled; if no definition is supplied, the symbol-function of the symbol is
extracted and compiled. It is permissible for the symbol to have a macro
definition rather than a function definition; both macros and functions may be
compiled.
It is an error if the function to be compiled was defined interpretively in a
non-null lexical environment. (An implementation is free to extend the behavior
of compile to compile such functions properly, but portable programs may not
depend on this capability.) The consequences of calling compile on a function
that is already compiled are unspecified.
[change_end]
[old_change_begin]
The definition is compiled and a compiled-function object produced. If name is
a non-nil symbol, then the compiled-function object is installed as the global
function definition of the symbol and the symbol is returned. If name is nil,
then the compiled-function object itself is returned. For example:
(defun foo ...) => foo ØA function definition
(compile 'foo) => foo ;Compile it
;Now foo runs faster (maybe)
(compile nil
'(lambda (a b c) (- (* b b) (* 4 a c))))
=> a compiled function of three arguments that computes
[old_change_end]
[change_begin]
X3J13 voted in June 1989 (COMPILER-DIAGNOSTICS) to specify that compile
returns two additional values indicating whether the compiler issued any
diagnostics (see section 25.1.1).
X3J13 voted in March 1989 (FUNCTION-NAME) to extend compile to accept as a
name any function-name (a symbol or a list whose car is setf-see section 7.1).
One may write (compile '(setf cadr)) to compile the setf expansion function for
cadr.
[change_end]
[old_change_begin]
[Function]
compile-file input-pathname &key :output-file
The input-pathname must be a valid file specifier, such as a pathname. The
defaults for input-filename are taken from the variable
*default-pathname-defaults*. The file should be a Lisp source file; its
contents are compiled and written as a binary object file.
[old_change_end]
[change_begin]
X3J13 voted in March 1989 (COMPILER-VERBOSITY) to add two new keyword
arguments :verbose and :print to compile-file by analogy with load. The new
function definition is as follows.
[Function]
compile-file input-pathname &key :output-file :verbose :print
The :verbose argument (which defaults to the value of *compile-verbose*), if
true, permits compile-file to print a message in the form of a comment to
*standard-output* indicating what file is being compiled and other useful
information.
The :print argument (which defaults to the value of *compile-print*), if true,
causes information about top-level forms in the file being compiled to be
printed to *standard-output*. Exactly what is printed is
implementation-dependent; nevertheless something will be printed.
X3J13 voted in March 1988 (PATHNAME-STREAM) to specify exactly which streams
may be used as pathnames (see section 23.1.6).
X3J13 voted in June 1989 (PATHNAME-WILD) to clarify that supplying a wild
pathname as the input-pathname argument to compile-file has
implementation-dependent consequences; compile-file might signal an error, for
example, or might compile all files that match the wild pathname.
X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require compile-file to accept
logical pathnames (see section 23.1.5).
[change_end]
The :output-file argument may be used to specify an output pathname; it
defaults in a manner appropriate to the implementation's file system
conventions.
[change_begin]
X3J13 voted in June 1989 (COMPILER-DIAGNOSTICS) to specify that compile-file
returns three values: the truename of the output file (or nil if the file could
not be created) and two values indicating whether the compiler issued any
diagnostics (see section 25.1.1).
X3J13 voted in October 1988 (COMPILE-FILE-PACKAGE) to specify that
compile-file, like load, rebinds *package* to its current value. If some form
in the file changes the value of *package*, the old value will be restored when
compilation is completed.
X3J13 voted in June 1989 (COMPILE-FILE-SYMBOL-HANDLING) to specify
restrictions on conforming programs to ensure consistent handling of symbols
and packages.
In order to guarantee that compiled files can be loaded correctly, the user
must ensure that the packages referenced in the file are defined consistently
at compile and load time. Conforming Common Lisp programs must satisfy the
following requirements.
* The value of *package* when a top-level form in the file is processed by
compile-file must be the same as the value of *package* when the code
corresponding to that top-level form in the compiled file is executed by
the loader. In particular, any top-level form in a file that alters the
value of *package* must change it to a package of the same name at both
compile and load time; moreover, if the first non-atomic top-level form in
the file is not a call to in-package, then the value of *package* at the
time load is called must be a package with the same name as the package
that was the value of *package* at the time compile-file was called.
* For every symbol appearing lexically within a top-level form that was
accessible in the package that was the value of *package* during
processing of that top-level form at compile time, but whose home package
was another package, at load time there must be a symbol with the same
name that is accessible in both the load-time *package* and in the package
with the same name as the compile-time home package.
* For every symbol in the compiled file that was an external symbol in its
home package at compile time, there must be a symbol with the same name
that is an external symbol in the package with the same name at load time.
If any of these conditions do not hold, the package in which load looks for the
affected symbols is unspecified. Implementations are permitted to signal an
error or otherwise define this behavior.
These requirements are merely an explicit statement of the status quo, namely
that users cannot depend on any particular behavior if the package environment
at load time is inconsistent with what existed at compile time.
X3J13 voted in March 1989 (IN-SYNTAX) to specify that compile-file must bind
*readtable* to its current value at the time compile-file is called; the
dynamic extent of the binding should encompass all of the file-loading
activity. This allows a portable program to include forms such as
(in-package "FOO")
(eval-when (:execute :load-toplevel :compile-toplevel)
(setq *readtable* foo:my-readtable))
without performing a net global side effect on the loading environment. Such
statements allow the remainder of such a file to be read either as interpreted
code or by compile-file in a syntax determined by an alternative readtable.
X3J13 voted in June 1989 (LOAD-TRUENAME) to require that compile-file bind
two new variables *compile-file-pathname* and *compile-file-truename*; the
dynamic extent of the bindings should encompass all of the file-compiling
activity.
[Variable]
*compile-verbose*
X3J13 voted in March 1989 (COMPILER-VERBOSITY) to add *compile-verbose*. This
variable provides the default for the :verbose argument to compile-file. Its
initial value is implementation-dependent.
A proposal was submitted to X3J13 in October 1989 to rename this
*compile-file-verbose* for consistency.
[Variable]
*compile-print*
X3J13 voted in March 1989 (COMPILER-VERBOSITY) to add *compile-print*. This
variable provides the default for the :print argument to compile-file. Its
initial value is implementation-dependent.
A proposal was submitted to X3J13 in October 1989 to rename this
*compile-file-print* for consistency.
[Variable]
*compile-file-pathname*
X3J13 voted in June 1989 (LOAD-TRUENAME) to introduce
*compile-file-pathname*; it is initially nil but compile-file binds it to a
pathname that represents the file name given as the first argument to
compile-file merged with the defaults (see merge-pathname).
[Variable]
*compile-file-truename*
X3J13 voted in June 1989 (LOAD-TRUENAME) to introduce
*compile-file-truename*; it is initially nil but compile-file binds it to the
``true name'' of the pathname of the file being compiled. See truename.
[Special Form]
load-time-value form [read-only-p]
X3J13 voted in March 1989 (LOAD-TIME-EVAL) to add a mechanism for delaying
evaluation of a form until it can be done in the run-time environment.
If a load-time-value expression is seen by compile-file, the compiler performs
its normal semantic processing (such as macro expansion and translation into
machine code) on the form, but arranges for the execution of the form to occur
at load time in a null lexical environment, with the result of this evaluation
then being treated as an immediate quantity (that is, as if originally quoted)
at run time. It is guaranteed that the evaluation of the form will take place
only once when the file is loaded, but the order of evaluation with respect to
the execution of top-level forms in the file is unspecified.
If a load-time-value expression appears within a function compiled with
compile, the form is evaluated at compile time in a null lexical environment.
The result of this compile-time evaluation is treated as an immediate quantity
in the compiled code.
In interpreted code, form is evaluated (by eval) in a null lexical environment
and one value is returned. Implementations that implicitly compile (or
partially compile) expressions passed to eval may evaluate the form only once,
at the time this compilation is performed. This is intentionally similar to the
freedom that implementations are given for the time of expanding macros in
interpreted code.
If the same (as determined by eq) list (load-time-value form) is evaluated or
compiled more than once, it is unspecified whether the form is evaluated only
once or is evaluated more than once. This can happen both when an expression
being evaluated or compiled shares substructure and when the same expression is
passed to eval or to compile multiple times. Since a load-time-value expression
may be referenced in more than one place and may be evaluated multiple times by
the interpreter, it is unspecified whether each execution returns a ``fresh''
object or returns the same object as some other execution. Users must use
caution when destructively modifying the resulting object.
If two lists (load-time-value form) are equal but not eq, their values always
come from distinct evaluations of form. Coalescing of these forms is not
permitted.
The optional read-only-p argument designates whether the result may be
considered a read-only constant. If nil (the default), the result must be
considered ordinary, modifiable data. If t, the result is a read-only quantity
that may, as appropriate, be copied into read-only space and may, as
appropriate, be shared with other programs. The read-only-p argument is not
evaluated and only the literal symbols t and nil are permitted.
This new feature addresses the same set of needs as the now-defunct #, reader
syntax but in a cleaner and more general manner. Note that #, syntax was
reliably useful only inside quoted structure (though this was not explicitly
mentioned in the first edition), whereas a load-time-value form must appear
outside quoted structure in a for-evaluation position.
See make-load-form.
[change_end]
[Function]
disassemble name-or-compiled-function
The argument should be a function object, a lambda-expression, or a symbol with
a function definition. If the relevant function is not a compiled function, it
is first compiled. In any case, the compiled code is then ``reverse-assembled''
and printed out in a symbolic format. This is primarily useful for debugging
the compiler, but also often of use to the novice who wishes to understand the
workings of compiled code.
-------------------------------------------------------------------------------
Implementation note: Implementors are encouraged to make the output readable,
preferably with helpful comments.
-------------------------------------------------------------------------------
[change_begin]
X3J13 voted in March 1988 (DISASSEMBLE-SIDE-EFFECT) to clarify that when
disassemble compiles a function, it never installs the resulting
compiled-function object in the symbol-function of a symbol.
X3J13 voted in March 1989 (FUNCTION-NAME) to extend disassemble to accept as
a name any function-name (a symbol or a list whose car is setf - see section
7.1). Thus one may write (disassemble '(setf cadr)) to disassemble the setf
expansion function for cadr.
[Function]
function-lambda-expression fn
X3J13 voted in January 1989 (FUNCTION-DEFINITION) to add a new function to
allow the source code for a defined function to be recovered. (The committee
noted that the first edition provided no portable way to recover a
lambda-expression once it had been compiled or evaluated to produce a
function.)
This function takes one argument, which must be a function, and returns three
values.
The first value is the defining lambda-expression for the function, or nil if
that information is not available. The lambda-expression may have been
preprocessed in some ways but should nevertheless be of a form suitable as an
argument to the function compile or for use in the function special form.
The second value is nil if the function was definitely produced by closing a
lambda-expression in the null lexical environment; it is some non-nil value if
the function might have been closed in some non-null lexical environment.
The third value is the ``name'' of the function; this is nil if the name is not
available or if the function had no name. The name is intended for debugging
purposes only and may be any Lisp object (not necessarily one that would be
valid for use as a name in a defun or function special form, for example).
-------------------------------------------------------------------------------
Implementation note: An implementation is always free to return the values nil,
t, nil from this function but is encouraged to make more useful information
available as appropriate. For example, it may not be desirable for files of
compiled code to retain the source lambda-expressions for use after the file is
loaded, but it is probably desirable for functions produced by ``in-core''
calls to eval, compile, or defun to retain the defining lambda-expression for
debugging purposes. The function function-lambda-expression makes this
information, if retained, accessible in a standard and portable manner.
-------------------------------------------------------------------------------
[Macro]
with-compilation-unit ({option-name option-value}*) {form}*
X3J13 voted in March 1989 (WITH-COMPILATION-UNIT) to add
with-compilation-unit, which executes the body forms as an implicit progn.
Within the dynamic context of this form, warnings deferred by the compiler
until ``the end of compilation'' will be deferred until the end of the
outermost call to with-compilation-unit. The results are the same as those of
the last of the forms (or nil if there is no form).
Each option-name is an unevaluated keyword; each option-value is evaluated. The
set of keywords permitted may be extended by the implementation, but the only
standard option keyword is :override; the default value for this option is nil.
If with-compilation-unit forms are nested dynamically, only the outermost such
call has any effect unless the :override value of an inner call is true.
The function compile-file should provide the effect of
(with-compilation-unit (:override nil) ...)
around its code.
Any implementation-dependent extensions to this behavior may be provided only
as the result of an explicit programmer request by use of an
implementation-dependent keyword. It is forbidden for an implementation to
attach additional meaning to a conforming use of this macro.
Note that not all compiler warnings are deferred. In some implementations, it
may be that none are deferred. This macro only creates an interface to the
capability where it exists, it does not require the creation of the capability.
An implementation that does not defer any compiler warnings may correctly
implement this macro as an expansion into a simple progn.
[change_end]
-------------------------------------------------------------------------------
* Compiler Diagnostics
* Compiled Functions
* Compilation Environment
* Similarity of Constants
-------------------------------------------------------------------------------
25.1.1. Compiler Diagnostics
[change_begin]
X3J13 voted in June 1987 (COMPILER-WARNING-STREAM) to specify that compile
and compile-file may output warning messages; any such messages should go to
the stream that is the value of *error-output*.
X3J13 voted in June 1989 (COMPILER-DIAGNOSTICS) to specify the use of
conditions to signal various erroneous situations during compilation. First,
note that error and warning conditions may be signaled either by the compiler
itself or by code being processed by the compiler (for example, arbitrary
errors may occur during compile-time macro expansion or processing of eval-when
forms). Considering only those conditions signaled by the compiler (as opposed
to during compilation):
* Conditions of type error may be signaled by the compiler in situations
where the compilation cannot proceed without intervention. Examples of
such situations may include errors when opening a file or syntax errors.
* Conditions of type warning may be signaled by the compiler in situations
where the standard explicitly states that a warning must, should, or may
be signaled. They may also be signaled when the compiler can determine
that a situation would result at runtime that would have undefined
consequences or would cause an error to be signaled. Examples of such
situations may include violations of type declarations, altering or
rebinding a constant defined with defconstant, calls to built-in Lisp
functions with too few or too many arguments or with malformed keyword
argument lists, referring to a variable declared ignore, or unrecognized
declaration specifiers.
* The compiler is permitted to signal diagnostics about matters of
programming style as conditions of type style-warning, a subtype of
warning. Although a style-warning condition may be signaled in these
situations, no implementation is required to do so. However, if an
implementation does choose to signal a condition, that condition will be
of type style-warning and will be signaled by a call to the function warn.
Examples of such situations may include redefinition of a function with an
incompatible argument list, calls to functions (other than built-in
functions) with too few or too many arguments or with malformed keyword
argument lists, unreferenced local variables not declared ignore, or
standard declaration specifiers that are ignored by the particular
compiler in question.
Both compile and compile-file are permitted (but not required) to establish a
handler for conditions of type error. Such a handler might, for example, issue
a warning and restart compilation from some implementation-dependent point in
order to let the compilation proceed without manual intervention.
The functions compile and compile-file each return three values. See the
definitions of these functions for descriptions of the first value. The second
value is nil if no compiler diagnostics were issued, and true otherwise. The
third value is nil if no compiler diagnostics other than style warnings were
issued; a non-nil value indicates that there were ``serious'' compiler
diagnostics issued or that other conditions of type error or warning (but not
style-warning) were signaled during compilation.
[change_end]
-------------------------------------------------------------------------------
25.1.2. Compiled Functions
[change_begin]
X3J13 voted in June 1989 (COMPILED-FUNCTION-REQUIREMENTS) to impose certain
requirements on the functions produced by the compilation process.
If a function is of type compiled-function, then all macro calls appearing
lexically within the function have already been expanded and will not be
expanded again when the function is called. The process of compilation
effectively turns every macrolet or symbol-macrolet construct into a progn (or
a locally) with all instances of the local macros in the body fully expanded.
If a function is of type compiled-function, then all load-time-value forms
appearing lexically within the function have already been pre-evaluated and
will not be evaluated again when the function is called.
Implementations are free to classify every function as a compiled-function
provided that all functions satisfy the preceding requirements. Conversely, it
is permissible for a function that is not a compiled-function to satisfy the
preceding requirements.
If one or more functions are defined in a file that is compiled with
compile-file and the compiled file is subsequently loaded by the function load,
the resulting loaded function definitions must be of type compiled-function.
The function compile must produce an object of type compiled-function as the
value that is either returned or stored into the symbol-function of a symbol
argument.
Note that none of these restrictions addresses questions of the compilation
technology or target instruction set. For example, a compiled function does not
necessarily consist of native machine instructions. These requirements merely
specify the behavior of the type system with respect to certain actions taken
by compile, compile-file, and load.
[change_end]
-------------------------------------------------------------------------------
25.1.3. Compilation Environment
[change_begin]
X3J13 voted in June 1989 (COMPILE-ENVIRONMENT-CONSISTENCY) to specify what
information must be available at compile time for correct compilation and what
need not be available until run time.
The following information must be present in the compile-time environment for a
program to be compiled correctly. This information need not also be present in
the run-time environment.
* In conforming code, macros referenced in the code being compiled must
have been previously defined in the compile-time environment. The compiler
must treat as a function call any form that is a list whose car is a
symbol that does not name a macro or special form. (This implies that setf
methods must also be available at compile time.)
* In conforming code, proclamations for special variables must be made in
the compile-time environment before any bindings of those variables are
processed by the compiler. The compiler must treat any binding of an
undeclared variable as a lexical binding.
The compiler may incorporate the following kinds of information into the code
it produces, if the information is present in the compile-time environment and
is referenced within the code being compiled; however, the compiler is not
required to do so. When compile-time and run-time definitions differ, it is
unspecified which will prevail within the compiled code (unless some other
behavior is explicitly specified below). It is also permissible for an
implementation to signal an error at run time on detecting such a discrepancy.
In all cases, the absence of the information at compile time is not an error,
but its presence may enable the compiler to generate more efficient code.
* The compiler may assume that functions that are defined and declared
inline in the compile-time environment will retain the same definitions at
run time.
* The compiler may assume that, within a named function, a recursive call
to a function of the same name refers to the same function, unless that
function has been declared notinline. (This permits tail-recursive calls
of a function to itself to be compiled as jumps, for example, thereby
turning certain recursive schemas into efficient loops.)
* In the absence of notinline declarations to the contrary, compile-file
may assume that a call within the file being compiled to a named function
that is defined in that file refers to that function. (This rule permits
block compilation of files.) The behavior of the program is unspecified if
functions are redefined individually at run time.
* The compiler may assume that the signature (or ``interface contract'') of
all built-in Common Lisp functions will not change. In addition, the
compiler may treat all built-in Common Lisp functions as if they had been
proclaimed inline.
* The compiler may assume that the signature (or ``interface contract'') of
functions with ftype information available will not change.
* The compiler may ``wire in'' (that is, open-code or inline) the values of
symbolic constants that have been defined with defconstant in the
compile-time environment.
* The compiler may assume that any type definition made with defstruct or
deftype in the compile-time environment will retain the same definition in
the run-time environment. It may also assume that a class defined by
defclass in the compile-time environment will be defined in the run-time
environment in such a way as to have the same superclasses and metaclass.
This implies that subtype/supertype relationships of type specifiers will
not change between compile time and run time. (Note that it is not an
error for an unknown type to appear in a declaration at compile time,
although it is reasonable for the compiler to emit a warning in such a
case.)
* The compiler may assume that if type declarations are present in the
compile-time environment, the corresponding variables and functions
present in the run-time environment will actually be of those types. If
this assumption is violated, the run-time behavior of the program is
undefined.
The compiler must not make any additional assumptions about consistency between
the compile-time and run-time environments. In particular, the compiler may not
assume that functions that are defined in the compile-time environment will
retain either the same definition or the same signature at run time, except as
described above. Similarly, the compiler may not signal an error if it sees a
call to a function that is not defined at compile time, since that function may
be provided at run time.
X3J13 voted in January 1989 (COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS) to
specify the compile-time side effects of processing various macro forms.
Calls to defining macros such as defmacro or defvar appearing within a file
being processed by compile-file normally have compile-time side effects that
affect how subsequent forms in the same file are compiled. A convenient model
for explaining how these side effects happen is that each defining macro
expands into one or more eval-when forms and that compile-time side effects are
caused by calls occurring in the body of an (eval-when (:compile-toplevel) ...)
form.
The affected defining macros and their specific side effects are as follows. In
each case, it is identified what a user must do to ensure that a program is
conforming, and what a compiler must do in order to correctly process a
conforming program.
deftype
The user must ensure that the body of a deftype form is evaluable at
compile time if the type is referenced in subsequent type declarations.
The compiler must ensure that a type specifier defined by deftype is
recognized in subsequent type declarations. If the expansion of a type
specifier is not defined fully at compile time (perhaps because it expands
into an unknown type specifier or a satisfies of a named function that
isn't defined in the compile-time environment), an implementation may
ignore any references to this type in declarations and may signal a
warning.
defmacro and define-modify-macro
The compiler must store macro definitions at compile time, so that
occurrences of the macro later on in the file can be expanded correctly.
The user must ensure that the body of the macro is evaluable at compile
time if it is referenced within the file being compiled.
defun
No required compile-time side effects are associated with defun forms. In
particular, defun does not make the function definition available at
compile time. An implementation may choose to store information about the
function for the purposes of compile-time error checking (such as checking
the number of arguments on calls) or to permit later inline expansion of
the function.
defvar and defparameter
The compiler must recognize that the variables named by these forms have
been proclaimed special. However, it must not evaluate the initial-value
form or set the variable at compile time.
defconstant
The compiler must recognize that the symbol names a constant. An
implementation may choose to evaluate the value-form at compile time, load
time, or both. Therefore the user must ensure that the value-form is
evaluable at compile time (regardless of whether or not references to the
constant appear in the file) and that it always evaluates to the same
value. (There has been considerable variance among implementations on this
point. The effect of this specification is to legitimize all of the
implementation variants by requiring care of the user.)
defsetf and define-setf-method
The compiler must make setf methods available so that they may be used to
expand calls to setf later on in the file. Users must ensure that the body
of a call to define-setf-method or the complex form of defsetf is
evaluable at compile time if the corresponding place is referred to in a
subsequent setf in the same file. The compiler must make these setf
methods available to compile-time calls to get-setf-method when its
environment argument is a value received as the &environment parameter of
a macro.
defstruct
The compiler must make the structure type name recognized as a valid type
name in subsequent declarations (as described above for deftype) and make
the structure slot accessors known to setf. In addition, the compiler must
save enough information so that further defstruct definitions can include
(with the :include option) a structure type defined earlier in the file
being compiled. The functions that defstruct generates are not defined in
the compile-time environment, although the compiler may save enough
information about the functions to allow inline expansion of subsequent
calls to these functions. The #S reader syntax may or may not be available
for that structure type at compile time.
define-condition
The rules are essentially the same as those for defstruct. The compiler
must make the condition type recognizable as a valid type name, and it
must be possible to reference the condition type as the parent-type of
another condition type in a subsequent define-condition form in the file
being compiled.
defpackage
All of the actions normally performed by the defpackage macro at load time
must also be performed at compile time.
Compile-time side effects may cause information about a definition to be stored
in a different manner from information about definitions processed either
interpretively or by loading a compiled file. In particular, the information
stored by a defining macro at compile time may or may not be available to the
interpreter (either during or after compilation) or during subsequent calls to
compile or compile-file. For example, the following code is not portable
because it assumes that the compiler stores the macro definition of foo where
it is available to the interpreter.
(defmacro foo (x) `(car ,x))
(eval-when (:execute :compile-toplevel :load-toplevel)
(print (foo '(a b c)))) ;Wrong
The goal may be accomplished portably by including the macro definition within
the eval-when form:
(eval-when (eval compile load)
(defmacro foo (x) `(car ,x))
(print (foo '(a b c)))) ;Right
declaim
X3J13 voted in June 1989 (PROCLAIM-ETC-IN-COMPILE-FILE) to add a new
macro declaim for making proclamations recognizable at compile time. The
declaration specifiers in the declaim form are effectively proclaimed at
compile time so as to affect compilation of subsequent forms. (Note that
compiler processing of a call to proclaim does not have any compile-time
side effects, for proclaim is a function.)
in-package
X3J13 voted in March 1989 (IN-PACKAGE-FUNCTIONALITY) to specify that all
of the actions normally performed by the in-package macro at load time
must also be performed at compile time.
X3J13 voted in June 1989 (CLOS-MACRO-COMPILATION) to specify the compile-time
side effects of processing various CLOS-related macro forms. Top-level calls to
the CLOS defining macros have the following compile-time side effects; any
other compile-time behavior is explicitly left unspecified.
defclass
The class name may appear in subsequent type declarations and can be used
as a specializer in subsequent defmethod forms. Thus the compile-time
behavior of defclass is similar to that of deftype or defstruct.
defgeneric
The generic function can be referenced in subsequent defmethod forms, but
the compiler does not arrange for the generic function to be callable at
compile time.
defmethod
The compiler does not arrange for the method to be callable at compile
time. If there is a generic function with the same name defined at compile
time, compiling a defmethod form does not add the method to that generic
function; the method is added to the generic function only when the
defmethod form is actually executed.
The error-signaling behavior described in the specification of defmethod
in chapter 28 (if the function isn't a generic function or if the
lambda-list is not congruent) occurs only when the defining form is
executed, not at compile time.
The forms in eql parameter specializers are evaluated when the defmethod
form is executed. The compiler is permitted to build in knowledge about
what the form in an eql specializer will evaluate to in cases where the
ultimate result can be syntactically inferred without actually evaluating
it.
define-method-combination
The method combination can be used in subsequent defgeneric forms.
The body of a define-method-combination form is evaluated no earlier than
when the defining macro is executed and possibly as late as generic
function invocation time. The compiler may attempt to evaluate these forms
at compile time but must not depend on being able to do so.
[change_end]
-------------------------------------------------------------------------------
25.1.4. Similarity of Constants
[change_begin]
X3J13 voted in March 1989 (CONSTANT-COMPILABLE-TYPES) to specify what objects
can be in compiled constants and what relationship there must be between a
constant passed to the compiler and the one that is established by compiling it
and then loading its file.
The key is a definition of an equivalence relationship called ``similarity as
constants'' between Lisp objects. Code passed through the file compiler and
then loaded must behave as though quoted constants in it are similar in this
sense to quoted constants in the corresponding source code. An object may be
used as a quoted constant processed by compile-file if and only if the compiler
can guarantee that the resulting constant established by loading the compiled
file is ``similar as a constant'' to the original. Specific requirements are
spelled out below.
Some types of objects, such as streams, are not supported in constants
processed by the file compiler. Such objects may not portably appear as
constants in code processed with compile-file. Conforming implementations are
required to handle such objects either by having the compiler or loader
reconstruct an equivalent copy of the object in some implementation-specific
manner or by having the compiler signal an error.
Of the types supported in constants, some are treated as aggregate objects. For
these types, being similar as constants is defined recursively. We say that an
object of such a type has certain ``basic attributes''; to be similar as a
constant to another object, the values of the corresponding attributes of the
two objects must also be similar as constants.
A definition of this recursive form has problems with any circular or
infinitely recursive object such as a list that is an element of itself. We use
the idea of depth-limited comparison and say that two objects are similar as
constants if they are similar at all finite levels. This idea is implicit in
the definitions below, and it applies in all the places where attributes of two
objects are required to be similar as constants. The question of handling
circular constants is the subject of a separate vote by X3J13 (see below).
The following terms are used throughout this section. The term constant refers
to a quoted or self-evaluating constant, not a named constant defined by
defconstant. The term source code is used to refer to the objects constructed
when compile-file calls read (or the equivalent) and to additional objects
constructed by macro expansion during file compilation. The term compiled code
is used to refer to objects constructed by load.
Two objects are similar as a constant if and only if they are both of one of
the types listed below and satisfy the additional requirements listed for that
type.
number
Two numbers are similar as constants if they are of the same type and
represent the same mathematical value.
character
Two characters are similar as constants if they both represent the same
character. (The intent is that this be compatible with how eql is defined
on characters.)
symbol
X3J13 voted in June 1989 (COMPILE-FILE-SYMBOL-HANDLING) to define
similarity as a constant for interned symbols. A symbol S appearing in the
source code is similar as a constant to a symbol S' in the compiled code
if their print names are similar as constants and either of the following
conditions holds:
o S is accessible in *package* at compile time and S' is accessible in
*package* at load time.
o S' is accessible in the package that is similar as a constant to the
home package of symbol S.
The ``similar as constants'' relationship for interned symbols has nothing
to do with *readtable* or how the function read would parse the characters
in the print name of the symbol.
An uninterned symbol in the source code is similar as a constant to an
uninterned symbol in the compiled code if their print names are similar as
constants.
package
A package in the source code is similar as a constant to a package in the
compiled code if their names are similar as constants. Note that the
loader finds the corresponding package object as if by calling
find-package with the package name as an argument. An error is signaled if
no package of that name exists at load time.
random-state
We say that two random-state objects are functionally equivalent if
applying random to them repeatedly always produces the same pseudo-random
numbers in the same order.
Two random-states are similar as constants if and only if copies of them
made via make-random-state are functionally equivalent. (Note that a
constant random-state object cannot be used as the state argument to the
function random because random performs a side effect on that argument.)
cons
Two conses are similar as constants if the values of their respective car
and cdr attributes are similar as constants.
array
Two arrays are similar as constants if the corresponding values of each of
the following attributes are similar as constants: for vectors
(one-dimensional arrays), the length and element-type and the result of
elt for all valid indices; for all other arrays, the array-rank, the
result of array-dimension for all valid axis numbers, the
array-element-type, and the result of aref for all valid indices. (The
point of distinguishing vectors is to take any fill pointers into
account.)
If the array in the source code is a simple-array, then the corresponding
array in the compiled code must also be a simple-array, but if the array
in the source code is displaced, has a fill pointer, or is adjustable, the
corresponding array in the compiled code is permitted to lack any or all
of these qualities.
hash-table
Two hash tables are similar as constants if they meet three requirements.
First, they must have the same test (for example, both are eql hash tables
or both are equal hash tables). Second, there must be a unique bijective
correspondence between the keys of the two tables, such that the
corresponding keys are similar as constants. Third, for all keys, the
values associated with two corresponding keys must be similar as
constants.
If there is more than one possible one-to-one correspondence between the
keys of the two tables, it is unspecified whether the two tables are
similar as constants. A conforming program cannot use such a table as a
constant.
pathname
Two pathnames are similar as constants if all corresponding pathname
components are similar as constants.
stream, readtable, and method
Objects of these types are not supported in compiled constants.
function
X3J13 voted in June 1989 (CONSTANT-FUNCTION-COMPILATION) to specify that
objects of type function are not supported in compiled constants.
structure and standard-object
X3J13 voted in March 1989 (LOAD-OBJECTS) to introduce a facility based
on the Common Lisp Object System whereby a user can specify how
compile-file and load must cooperate to reconstruct compile-time constant
objects at load time (see make-load-form).
X3J13 voted in March 1989 (CONSTANT-COLLAPSING) to specify the circumstances
under which constants may be coalesced in compiled code.
Suppose A and B are two objects used as quoted constants in the source code,
and that A' and B' are the corresponding objects in the compiled code. If A'
and B' are eql but A and B were not eql, then we say that A and B have been
coalesced by the compiler.
An implementation is permitted to coalesce constants appearing in code to be
compiled if and only if they are similar as constants, except that objects of
type symbol, package, structure, or standard-object obey their own rules and
may not be coalesced by a separate mechanism.
-------------------------------------------------------------------------------
Rationale: Objects of type symbol and package cannot be coalesced because the
fact that they are named, interned objects means they are already as coalesced
as it is useful for them to be. Uninterned symbols could perhaps be coalesced,
but that was thought to be more dangerous than useful. Structures and objects
could be coalesced if a ``similar as a constant'' predicate were defined for
them; it would be a generic function. However, at present there is no such
predicate. Currently make-load-form provides a protocol by which compile-file
and load work together to construct an object in the compiled code that is
equivalent to the object in the source code; a different mechanism would have
to be added to permit coalescing.
-------------------------------------------------------------------------------
Note that coalescing is possible only because it is forbidden to destructively
modify constants (CONSTANT-MODIFICATION) (see quote).
X3J13 voted in March 1989 (CONSTANT-CIRCULAR-COMPILATION) to specify that
objects containing circular or infinitely recursive references may legitimately
appear as constants to be compiled. The compiler is required to preserve
eql-ness of substructures within a file compiled by compile-file.
[change_end]
-------------------------------------------------------------------------------
25.2. Documentation
[old_change_begin]
A simple facility is provided for attaching strings to symbols for the purpose
of on-line documentation. Rather than using the property list of the symbol, a
separate function documentation is provided so that implementations can
optimize the storage of documentation strings.
[Function]
documentation symbol doc-type
This function returns the documentation string of type doc-type for the symbol,
or nil if none exists. Both arguments must be symbols. Some kinds of
documentation are provided automatically by certain Common Lisp constructs if
the user writes an optional documentation string within them:
Construct Documentation Type
============================================
defvar variable
defparameter variable
defconstant variable
defun function
defmacro function
defstruct structure
deftype type
defsetf setf
============================================
In addition, names of special forms may also have function documentation.
(Macros and special forms are not really functions, of course, but it is
convenient to group them with functions for documentation purposes.)
setf may be used with documentation to update documentation information.
[old_change_end]
[change_begin]
X3J13 voted in June 1988 (CLOS) to make documentation a CLOS generic function
(see chapter 28).
X3J13 voted in March 1989 (FUNCTION-NAME) to extend documentation to accept
any function-name (a symbol or a list whose car is setf - see section 7.1).
Thus one may write (documentation '(setf cadr) 'function) to determine whether
there is any documentation for a setf expansion function for cadr.
[change_end]
-------------------------------------------------------------------------------
25.4. Environment Inquiries
Environment inquiry functions provide information about the environment in
which a Common Lisp program is being executed. They are described here in two
categories: first, those dealing with determination and measurement of time,
and second, all the others, most of which deal with identification of the
computer hardware and software.
-------------------------------------------------------------------------------
* Time Functions
* Other Environment Inquiries
-------------------------------------------------------------------------------
25.4.1. Time Functions
Time is represented in three different ways in Common Lisp: Decoded Time,
Universal Time, and Internal Time. The first two representations are used
primarily to represent calendar time and are precise only to one second.
Internal Time is used primarily to represent measurements of computer time
(such as run time) and is precise to some implementation-dependent fraction of
a second, as specified by internal-time-units-per-second. Decoded Time format
is used only for absolute time indications. Universal Time and Internal Time
formats are used for both absolute and relative times.
Decoded Time format represents calendar time as a number of components:
* Second: an integer between 0 and 59, inclusive.
* Minute: an integer between 0 and 59, inclusive.
* Hour: an integer between 0 and 23, inclusive.
* Date: an integer between 1 and 31, inclusive (the upper limit actually
depends on the month and year, of course).
* Month: an integer between 1 and 12, inclusive; 1 means January, 12 means
December.
* Year: an integer indicating the year A.D. However, if this integer is
between 0 and 99, the ``obvious'' year is used; more precisely, that year
is assumed that is equal to the integer modulo 100 and within fifty years
of the current year (inclusive backwards and exclusive forwards). Thus, in
the year 1978, year 28 is 1928 but year 27 is 2027. (Functions that return
time in this format always return a full year number.)
-------------------------------------------------------------------------------
Compatibility note: This is incompatible with the Lisp Machine Lisp definition
in two ways. First, in Lisp Machine Lisp a year between 0 and 99 always has
1900 added to it. Second, in Lisp Machine Lisp time functions return the
abbreviated year number between 0 and 99 rather than the full year number. The
incompatibility is prompted by the imminent arrival of the twenty-first
century. Note that (mod year 100) always reliably converts a year number to the
abbreviated form, while the inverse conversion can be very difficult.
-------------------------------------------------------------------------------
* Day-of-week: an integer between 0 and 6, inclusive; 0 means Monday, 1
means Tuesday, and so on; 6 means Sunday.
* Daylight-saving-time-p: a flag that, if not nil, indicates that daylight
saving time is in effect.
* Time-zone: an integer specified as the number of hours west of GMT
(Greenwich Mean Time). For example, in Massachusetts the time zone is 5,
and in California it is 8. Any adjustment for daylight saving time is
separate from this.
[change_begin]
X3J13 voted in March 1989 (TIME-ZONE-NON-INTEGER) to specify that the time
zone part of Decoded Time need not be an integer, but may be any rational
number (either an integer or a ratio) in the range -24 to 24 (inclusive on both
ends) that is an integral multiple of 1/3600.
-------------------------------------------------------------------------------
Rationale: For all possible time designations to be accommodated, it is
necessary to allow the time zone to be non-integral, for some places in the
world have time standards offset from Greenwich Mean Time by a non-integral
number of hours.
There appears to be no user demand for floating-point time zones. Since such
zones would introduce inexact arithmetic, X3J13 did not consider adding them at
this time.
This specification does require time zones to be represented as integral
multiples of 1 second (rather than 1 hour). This prevents problems that could
otherwise occur in converting Decoded Time to Universal Time.
-------------------------------------------------------------------------------
[change_end]
Universal Time represents time as a single non-negative integer. For relative
time purposes, this is a number of seconds. For absolute time, this is the
number of seconds since midnight, January 1, 1900 GMT. Thus the time 1 is
00:00:01 (that is, 12:00:01 A.M.) on January 1, 1900 GMT. Similarly, the time
2398291201 corresponds to time 00:00:01 on January 1, 1976 GMT. Recall that the
year 1900 was not a leap year; for the purposes of Common Lisp, a year is a
leap year if and only if its number is divisible by 4, except that years
divisible by 100 are not leap years, except that years divisible by 400 are
leap years. Therefore the year 2000 will be a leap year. (Note that the ``leap
seconds'' that are sporadically inserted by the world's official timekeepers as
an additional correction are ignored; Common Lisp assumes that every day is
exactly 86400 seconds long.) Universal Time format is used as a standard time
representation within the ARPANET; see reference [22]. Because the Common Lisp
Universal Time representation uses only non-negative integers, times before the
base time of midnight, January 1, 1900 GMT cannot be processed by Common Lisp.
Internal Time also represents time as a single integer, but in terms of an
implementation-dependent unit. Relative time is measured as a number of these
units. Absolute time is relative to an arbitrary time base, typically the time
at which the system began running.
[Function]
get-decoded-time
The current time is returned in Decoded Time format. Nine values are returned:
second, minute, hour, date, month, year, day-of-week, daylight-saving-time-p,
and time-zone.
-------------------------------------------------------------------------------
Compatibility note: In Lisp Machine Lisp time-zone is not currently returned.
Consider, however, the use of Common Lisp in some mobile vehicle. It is
entirely plausible that the time zone might change from time to time.
-------------------------------------------------------------------------------
[Function]
get-universal-time
The current time of day is returned as a single integer in Universal Time
format.
[Function]
decode-universal-time universal-time &optional time-zone
The time specified by universal-time in Universal Time format is converted to
Decoded Time format. Nine values are returned: second, minute, hour, date,
month, year, day-of-week, daylight-saving-time-p, and time-zone.
-------------------------------------------------------------------------------
Compatibility note: In Lisp Machine Lisp time-zone is not currently returned.
Consider, however, the use of Common Lisp in some mobile vehicle. It is
entirely plausible that the time zone might change from time to time.
-------------------------------------------------------------------------------
The time-zone argument defaults to the current time zone.
[change_begin]
X3J13 voted in January 1989 (DECODE-UNIVERSAL-TIME-DAYLIGHT) to specify that
decode-universal-time, like encode-universal-time, ignores daylight saving time
information if a time-zone is explicitly specified; in this case the returned
daylight-saving-time-p value will necessarily be nil even if daylight saving
time happens to be in effect in that time zone at the specified time.
[change_end]
[Function]
encode-universal-time second minute hour date month year &optional time-zone
The time specified by the given components of Decoded Time format is encoded
into Universal Time format and returned. If you do not specify time-zone, it
defaults to the current time zone adjusted for daylight saving time. If you
provide time-zone explicitly, no adjustment for daylight saving time is
performed.
[Constant]
internal-time-units-per-second
This value is an integer, the implementation-dependent number of internal time
units in a second. (The internal time unit must be chosen so that one second is
an integral multiple of it.)
-------------------------------------------------------------------------------
Rationale: The reason for allowing the internal time units to be
implementation-dependent is so that get-internal-run-time and
get-internal-real-time can execute with minimum overhead. The idea is that it
should be very likely that a fixnum will suffice as the returned value from
these functions. This probability can be tuned to the implementation by trading
off the speed of the machine against the word size. Any particular unit will be
inappropriate for some implementations: a microsecond is too long for a very
fast machine, while a much smaller unit would force many implementations to
return bignums for most calls to get-internal-time, rendering that function
less useful for accurate timing measurements.
-------------------------------------------------------------------------------
[Function]
get-internal-run-time
The current run time is returned as a single integer in Internal Time format.
The precise meaning of this quantity is implementation-dependent; it may
measure real time, run time, CPU cycles, or some other quantity. The intent is
that the difference between the values of two calls to this function be the
amount of time between the two calls during which computational effort was
expended on behalf of the executing program.
[Function]
get-internal-real-time
The current time is returned as a single integer in Internal Time format. This
time is relative to an arbitrary time base, but the difference between the
values of two calls to this function will be the amount of elapsed real time
between the two calls, measured in the units defined by
internal-time-units-per-second.
[Function]
sleep seconds
(sleep n) causes execution to cease and become dormant for approximately n
seconds of real time, whereupon execution is resumed. The argument may be any
non-negative non-complex number. sleep returns nil.
-------------------------------------------------------------------------------
25.4.2. Other Environment Inquiries
For any of the following functions, if no appropriate and relevant result can
be produced, nil is returned instead of a string.
-------------------------------------------------------------------------------
Rationale: These inquiry facilities are functions rather than variables against
the possibility that a Common Lisp process might migrate from machine to
machine. This need not happen in a distributed environment; consider, for
example, dumping a core image file containing a compiler and then shipping it
to another site.
-------------------------------------------------------------------------------
[Function]
lisp-implementation-type
A string is returned that identifies the generic name of the particular Common
Lisp implementation. Examples: "Spice LISP", "Zetalisp".
[Function]
lisp-implementation-version
A string is returned that identifies the version of the particular Common Lisp
implementation; this information should be of use to maintainers of the
implementation. Examples: "1192", "53.7 with complex numbers", "1746.9A, NEWIO
53, ETHER 5.3".
[Function]
machine-type
A string is returned that identifies the generic name of the computer hardware
on which Common Lisp is running. Examples: "IMLAC", "DEC PDP-10", "DEC
VAX-11/780".
[Function]
machine-version
A string is returned that identifies the version of the computer hardware on
which Common Lisp is running. Example: "KL10, microcode 9".
[Function]
machine-instance
A string is returned that identifies the particular instance of the computer
hardware on which Common Lisp is running; this might be a local nickname, for
example, or a serial number. Examples: "MIT-MC", "CMU GP-VAX".
[Function]
software-type
A string is returned that identifies the generic name of any relevant
supporting software. Examples: "Spice", "TOPS-20", "ITS".
[Function]
software-version
A string is returned that identifies the version of any relevant supporting
software; this information should be of use to maintainers of the
implementation.
[Function]
short-site-name
long-site-name
A string is returned that identifies the physical location of the computer
hardware. Examples of short names: "MIT AI Lab", "CMU-CSD". Examples of long
names:
"MIT Artificial Intelligence Laboratory"
"Massachusetts Institute of Technology
Artificial Intelligence Laboratory"
"Carnegie-Mellon University Computer Science Department"
See also user-homedir-pathname.
[Variable]
*features*
The value of the variable *features* should be a list of symbols that name
``features'' provided by the implementation. Most such names will be
implementation-specific; typically a name for the implementation will be
included.
[old_change_begin]
One standard feature name is ieee-floating-point, which should be present if
and only if full IEEE proposed floating-point arithmetic [23] is supported.
[old_change_end]
The value of this variable is used by the #+ and #- reader syntax.
[change_begin]
X3J13 voted in March 1988 (SHARPSIGN-PLUS-MINUS-PACKAGE) to specify that
feature names used with #+ and #- are read in the keyword package unless an
explicit prefix designating some other package appears. The standard feature
name ieee-floating-point is therefore actually the keyword
:ieee-floating-point, though one need not write the colon when using it with #+
or #-; thus #+ieee-floating-point and #+:ieee-floating-point mean the same
thing.
[change_end]
-------------------------------------------------------------------------------
25.5. Identity Function
This function is occasionally useful as an argument to other functions that
require functions as arguments. (Got that?)
[Function]
identity object
The object is returned as the value of identity.
[change_begin]
The identity function is the default value for the :key argument to many
sequence functions (see chapter 14).
Table 12-1 illustrates the behavior in the complex plane of the identity
function regarded as a function of a complex numerical argument.
Many other constructs in Common Lisp have the behavior of identity when given a
single argument. For example, one might well use values in place of identity.
However, writing values of a single argument conventionally indicates that the
argument form might deliver multiple values and that the intent is to pass on
only the first of those values.
-------------------------------------------------------------------------------
Compatibility note: In Maclisp, progn was a function of any number of arguments
that returned its last argument, so progn could be used as an identity
function. In Common Lisp, progn is a special form and therefore cannot be used
for that purpose.
-------------------------------------------------------------------------------
[change_end]
-------------------------------------------------------------------------------
